## -*- mode: html; coding: utf-8; -*-
## This file is part of CDS Invenio.
## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 CERN.
##
## CDS Invenio is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## CDS Invenio is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDS Invenio; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.


<!-- WebDoc-Page-Title: BibDocFile API -->
<!-- WebDoc-Page-Navtrail: <a class="navtrail" href="<CFG_SITE_URL>/help/hacking">Hacking CDS Invenio</a> -->
<!-- WebDoc-Page-Navbar-Select: hacking-websubmit-bibdocfile -->

<p>BibDocFile library handles every interaction relation between records and related fulltext document files.</p>

<h2>Nomenclature</h2>
<p>
<dl>
<dt>record</dt><dd>the unit of information within CDS Invenio. It is constituted by all the MARC metadata and have unique integer called <strong>Record ID</strong>.</dd>
<dt>fulltext</dt><dd>is a physical file connected to a record and often described by the record it self.</dd>
<dt>bibdoc</dt><dd>is an abstract document related to a record. It has a unique <strong>docname</strong> within the record, and is linked with multiple format and revision of fulltext files.</dd>
<dt>format (or extension)</dt><dd>is the extension associated with a physical file. Within a bibdoc, for a given version it can exist at most one file with a given format (e.g. .gif, .jpeg...)</dd>
<dt>version (or revision)</dt><dd>a progressive integer associated with a fulltext. The higher, the recent. Usually previous versions of a file are hidden.</dd>
</dl>
</p>

<h2>API</h2>
<p>Given a <tt>record_id</tt>, BibRecDocs(record_id) will be an object useful to represent all the bibdocs connected to a record.</p>

<p>Given a <tt>record_id</tt> and a <tt>docname</tt> or a <tt>document_id</tt>, BibDoc(recid=record_id, docname=docname) or BibDoc(docid=document_id) will be an object useful to represent all the possible version and formats of a document connected to a record.</p>

<p>By properly querying BibRecDocs and BibDoc you can obtain a BibDocFile. This is an object representing all the possible details related a single physical file, like a comment, a description, the path, the related URL, the size, the format, the version, the checksum, the protection...</p>

<p>Please refer to bibdocfile.py for a complete and up-to-date description of the API.</p>